package net.gdface.sdk.fse;

import net.gdface.annotation.DeriveMethod;

/**
 * 特征码内存搜索引擎(feature search engine)接口<br>
 * 提供高速的人脸特征相似度比对搜索/排序,支持多线程并行搜索，适用于百万级以上人脸库的快速搜索。<br>
 * 1.使用 {@link net.gdface.sdk.fse.FeatureSe#addFeature(byte[], byte[], String, int)}方法将特征添加到搜索引擎<br>
 * 2.使用 {@link net.gdface.sdk.fse.FeatureSe#searchCode(byte[], double, int, String[], int)}在内存中搜索与指定特征相似的的特征返回搜索结果
 * @author guyadong
 *
 */
public interface FeatureSe {
	/**
	 * 	在内存表中根据比对相似度进行特征码搜索
	 * @param code 要比对的特征码
	 * @param sim 相似度阀值
	 * @param rows  最大返回的记录数
	 * @param imgMD5Set 比对的图片范围
	 * @param group 特征分组,为{@code null}或0时,为全局特征搜索,否则只搜索特征分组掩码({@code CodeBean.group})匹配group的特征
	 * @return 返回包含相似度(降序)的结果数组,如果没有查到匹配的记录则返回空数组
	 */
	@DeriveMethod(methodSuffix="FromFse")
	public CodeBean[] searchCode(byte[] code, double sim, int rows, String[] imgMD5Set, int group);
	/**
	 * 根据特征码ID在表中查找指定的记录
	 * @param featureId 特征码ID,MD5校验码(16 bytes)
	 * @return 返回指定的特征记录,没有找到则返回{@code null},{@code featureId}为{@code null}或空返回{@code null}
	 */
	@DeriveMethod(methodSuffix="FromFse")
	public CodeBean getFeature(byte[] featureId);
	/**
	 * 根据特征码ID在表中查找指定的记录
	 * @param featureId 特征码ID,MD5校验码(32字节HEX字符串)
	 * @return 返回指定的特征记录,没有找到则返回{@code null},{@code featureId}为{@code null}或空返回{@code null}
	 */
	@DeriveMethod(methodSuffix="FromFse")
	public CodeBean getFeatureByHex(String featureId);
	/**
	 * 添加一条特征码到内存表<br>
	 * @param featureId 特征码ID(MD5校验码),为null时,native library会自动计算MD5作为特征码ID
	 * @param feature 特征码字节数组,为{@code null}时返回false
	 * @param imgMD5 特征所属图的MD5(32字节HEX字符串),可为null
	 * @param group 特征分组,为{@code null}或0则没有分组
	 * @return 添加成功返回true, 否则返回false
	 */
	@DeriveMethod(methodSuffix="ToFse")
	public boolean addFeature(byte[] featureId,byte[]feature, String imgMD5, int group);
	/**
	 * 添加一条特征码到内存表<br>
	 * @param featureId 特征码ID(MD5校验码),为null时,native library会自动计算MD5作为特征码ID
	 * @param feature 特征码字节数组,为{@code null}时返回false
	 * @param appid 应用id,由调用者定义,可为null
	 * @param group 特征分组,为{@code null}或0则没有分组
	 * @return 添加成功返回true, 否则返回false
	 */
	@DeriveMethod(methodSuffix="ToFseWithAppId")
	boolean addFeature(byte[] featureId, byte[] feature, long appid, int group);
	/**
	 * 更新特征码ID中表中指定的记录的特征分组
	 * @param featureId  特征码ID,MD5校验码(16 bytes)
	 * @param group 特征分组
	 * @return id为null或批不到特征记录返回false,更新成功返回true
	 */
	boolean updateGroup(byte[] featureId, int group);
	/**
	 * 根据特征码ID中表中删除指定的记录
	 * @param featureId  特征码ID,MD5校验码(16 bytes)
	 * @return 成功删除则返回true,否则返回false
	 */
	@DeriveMethod(methodSuffix="FromFse")
	public boolean removeFeature(byte[] featureId);
	/**
	 * 根据特征码ID中表中删除指定的记录
	 * @param featureId 特征码ID,MD5校验码(32字节HEX字符串)
	 * @return 成功删除则返回true,否则返回false
	 */
	@DeriveMethod(methodSuffix="FromFse")
	public boolean removeFeatureByHex(String featureId);
	/**
	 * 删除内存表中所有特征数据
	 */
	@DeriveMethod(methodSuffix="OfFse")
	public void clearAll();
	/**
	 * 
	 * @return 内存表中元素个数
	 */
	@DeriveMethod(methodSuffix="OfFse")
	public int size();
}
